FUNCTION
 DICE Linker

 SYNOPSIS
 dlink options files libraries

 DESCRIPTION
 The final step in creating an Amiga program is linking.  Normally the
 linker is invoked as needed by dcc or VMake.

 Options may occur anywhere on the command lines.  Any file ending in
 .o or .obj is assumed to be an object file.  Any file ending in .l or
 .lib is assumed to be a library.  Any file name beginning with @@
 specifies a text file containing a further list of files.

 File ordering is maintained.  Section ordering is maintained.  All
 sections of the same name are coagulated together with ordering
 maintained.

 || NOTE: Inter-section ordering is not maintained within a library
 || since library modules are random included.  However, ordering is
 || maintained *between* libraries.

 All object files specified are included in the final executable.  All
 libraries specified are searched at the point they are specified
 (that is, specifying an object file that references a symbol defined
 in a library specified BEFORE the object file will cause an undefined
 symbol error).  Normally an object file is specified after a library
 to terminate an autoinit or autoexit section.

 You do not have to order object files within a library, DLink will
 automatically make as many passes as required to handle all internal
 library references.  However, ordering object files will make DLink
 go faster.

 Symbols defined in object files override symbols defined in
 libraries. Symbols defined in libraries specified before later
 libraries override symbols defined in later libraries.  Symbols
 defined in a library and also defined in a later specified object
 module causes an error. -o execname name of executable

 -s  Include symbolic information.

     || NOTE: if -r is used symbolic info for the data sections will
     || point to the statically init'd stuff, NOT The actual data
     || space (in BSS) referenced by the code.  This is a bug.

  -frag  Fragment output file (default is to coagulate all hunks of the
     same type regardless of name).  If frag is specified then only
     hunks of the same type AND name are coagulated.

     see fragmentation note at bottom

 -r[es]  Resident link.

    -pi  Position independent non-residentable (i.e.  only one copy of the
     data but also no relocation hunks)

     -pr residentable position independent

 -Ppostfix  specify library name postfix.  If DLink cannot find the library
       as specified it will append the postfix and try again.  Used by
     DCC to specify the memory model.

 -mw addr  specify absolute data base

 -ma addr  specify absolute data base

     Both options do exactly the same thing and are in duplicate to
     conform to DCC's options.

 -mw
 -ma   specify the base of data as a decimal, 0octal, or 0xHEX address.
     You must use the -r option in conjunction with these options.

     DLink will resolve all Absolute-Word addresses but not all
     Absolute-Long addresses.  This is left up to the ROMABLE program
     which generates a raw binary image of the program that can then
     be transferred to an EPROM.

     || NOTE: Do not use this option when generating Amiga
     || executables.

  -d[#]  debug mode (spews lots of debugging junk out)

  -E file  specify stderr file, any errors are appended to the file instead
      of to stdout.  Useful for batch compiles

  -chip  chip-only - forces all hunks into CHIP memory

    -L0  remove default library search path, including all explicitly
     specified (-L dir) directories up to this point.

  -L dir  add the specified directory to the library search path.  If the
     object module or library can not be found in the current
     directory, directories specified with -L are searched.  -L
     directories are searched before the default library directory
     (DLIB:), assuming it was not removed with -L0 .

     Note that the directory path specified by -L is used to search
     for libraries AND object modules.

     A trailing '/' is optional

   -Ppostfix  This allows you to specify -lc -Ps and DLink will automatically
     look for cs.lib ...  you can specify a postfix that occurs before
     the .lib in the library name here.  If DLink cannot find the
     library as it is named by default it will try it with the
     postfix.

     DCC uses this to supply the memory model to DLINK also allowing
     the user to say -lm in DCC and have it find MS.LIB if you are
     using the small-data model.

 CREATING A LIBRARY
 DLink libraries are standard Amiga libraries...  simply join one or
 more object modules together and rename the result with a .lib
 extension.

 LINKER SYMBOLS
 DLink generates the following special symbols to aid in program
 startup:

 Symbol         : Meaning
 ===============+=====================================================
 __ABSOLUTE_BAS : Base of data in volatile space.  This symbol is NOT
            : defined for normal residentable programs since the
            : base address is not known (must be allocated
            : run-time)
 ---------------+-----------------------------------------------------
 __DATA_BAS     : Base of data in non-volatile space.  This symbol
            : points to a read-only copy of the initialized data
            : for a program.  For Non-residentable programs this
            : is the same as __ABSOLUTE_BAS. For residentable
            : programs this points to a read-only copy of the
            : initialized data that the program can duplicate on
            : startup. For programs linked with an absolute base
            : address for data this points to the end of the CODE
            : section.  The ROMABLE program always generates a
            : ROM copy of the initialized data just after the
            : CODE section (which startup code must copy into
            : RAM)
 ---------------+-----------------------------------------------------
 __DATA_LEN     : Length of data space is longwords.  i.e.
            : __DATA_LEN*4 yields the number of bytes of
            : initialized data.  This is used by startup code to
            : copy read-only initialized data to volatile space
            : (residentable and data-absolute programs)
 ---------------+-----------------------------------------------------
 __BSS_LEN      : Length of bss space in longwords.  i.e.
            : __BSS_LEN*4 yields the number of bytes of
            : uninitialized (BSS) data.  This is used in
            : combination with __DATA_LEN to allocate the
            : DATA+BSS space for residentable programs, and clear
            : the BSS space for non-residentable and
            : absolute-data-base programs.  The BSS space occurs
            : after the DATA space unless the -frag option is
            : used.
 ---------------+-----------------------------------------------------
 __RESIDENT5D   : This symbol is set to 0 if the -r option was used
            : and 1 if the -r option was not used.  If set to 1
            : (-r option)
 ---------------+-----------------------------------------------------

 Programs linked with the -mw or -ma options obviously do not
 'allocate' their data space since it is predefined.  Most Amiga
 programmers will never use the -mw or -ma options, by the way.

 SMALL DATA MODEL
 The small data model uses A4 relative addressing.  The linker sets up
 all relative offsets such that A4 must be initialized by startup code
 the BaseOfInitializedData + 32766 for A4-relative references to
 access the appropriate address.
   
 RESIDENT
 If the -r options is given then NO BSS SPACE is allocated after the
 data space...  the startup code MUST allocate a data+bss space as
 shown above.  DLink will give error messages for any absolute data
 references that occur (except the __DATA_BAS symbol which must be
 used to copy the static data to the newly allocated data+bss memory
 on program startup).
   
 DLink will give an error message if any data-data reloco32s exist
 when you specify the -r option as such relocations would be incorrect
 when copied to the newly allocated data+bss space.  DC1 understands
 this and will produce autoinit code to handle any such static data
 relocations that occur in your C code when the -r option is given to
 compile a C program.
   
 However, DLink does allow data-data relocations to occur if an
 absolute data base is specified along with the -r option.  This is
 used only when making ROMABLE code.
   
 PC-RELATIVE
 Because the linker will insert a jump table for PC-RELATIVE
 references to different hunks (after coagulation) or where the range
 is larger than +/-32K, data should not be placed into a code segment
 and be referenced via an external label(pc) unless you are positive
 the reference is within +/-32K.  This can only happen when
 referencing between like-named code hunks.  NOTE that the jump table
 is tagged onto the end of the section the jump(s) occur in and thus
 you do not want to have any autoinit/autoexit code that might
 possibly generate a jump table (since the whole idea with autoinit is
 that the code falls through to other autoinit code until the
 terminating section in x.o's RTS).
   
 Currently dlink cannot handle inter-module PC-RELATIVE references
 beyond +/-32K (i.e.  when one object file has more than 32K of code).
 An error will occur.
   
 Note that if -frag is used you cannot make PC-RELATIVE calls between
 sections of differing names ever, or make a program resident.  The
 -frag option is almost never used on untested.
   
 || NOTE: When -frag is specified, the linker will not create a
 || special combined data+bss hunk (so data and bss can both be
 || referenced with one base variable).
   
 However, when -frag is NOT specified, the linker will stil not
 necessarily combine ALL data hunks into one big hunk and ALL bss
 hunks into one big hunk.  Any data or bss hunk with special upper
 bits set (e.g. to force it into chip) is not combined into these
 special hunks, and any data or bss hunk whos NAME begins with 'far'
 (upper or lower case) will also not be considered.
   
 EXAMPLE
 This is what DCC gives the linker to link the program foo.c:
   
 dlink dlib:c.o @tmp dlib:x.o -o ram:foo
   
 Where tmp contains:
   
 foo.o
 dlib:c.lib
 dlib:amiga.lib
 dlib:auto.lib
   
 Basically it tells dlink to link the startup code, c.o, then the
 program object module(s) (foo.o), then c.lib, amiga.lib, and
 auto.lib, then finally x.o.
   
 DCC handles all this for you
   
 auto.lib contains autoinit code for certain selected libraries,
 including the dos.library.  Autoinit code is brought in whenever a
 given library base symbol has been referenced BUT NOT DEFINED.
 auto.lib defines the symbol and generates autoinit code to open the
 library and autoexit code to close the library.  To maintain
 portability you probably do not want to use this automatic
 library-opening feature yourself, it is really meant to support
 certain actions of the DICE library (such as floating point support).
   
 x.o terminates the autoinit and autoexit sections with an RTS
 instruction.  The autoinit and autoexit sections are called from the
 startup code c.o.